@starci/hfs 4.5.1 → 4.7.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 4.7.0 - 2026-10-18
+- Added: `app release push --execute` pushes the release sha to `release/candidate-<version>` and moves the branch and the tag only when its ci.yml run is green (RELEASE_CANDIDATE_CI_RED / _TIMEOUT, RELEASE_CI_UNKNOWN; the owner's sha-bound override record is the emergency path); the managed ci.yml and pre-push hook carry the candidate ref; R301 CI_STANDARD in the app check.
+- Added: the managed CI shards the unit run (`ci.jobs.test.shards`, default 6), lints each side in its own job and merges coverage in a coverage job (`starci app coverage merge`); `ci.jobs.<job>.timeoutMinutes`; jest/build caches keyed by the lockfile and saved always; `starci app ci local` runs the rendered jobs locally in parallel.
+- Fixed: a scaffolded app root overrides `@graphql-tools/utils` to the canon pin 12.1.0, closing GHSA-7mx3-vvmw-hjmv (npm audit high) under @nestjs/graphql 13.x.
+- Changed: `app release gate` no longer reads the default-branch CI (release/ci-red.mjs removed); the app trigger check allows the candidate branches.
+
+## 4.6.0 - 2026-10-18
+- Added: `services.codecov|sonar.badgeToken` README badge tokens and `ci.github.visibility` with a private-repository notice (sync, ci verify); `ci.vars` `ownerValue: true` (var sync skips, var set reads stdin, verify checks the name).
+- Fixed: the app release gate counts tag-push CI runs reachable from origin/main, main or HEAD; the secret scans exempt only declared badge tokens.
+- Fixed: empty placeholder lines vanish so every managed file is prettier-stable; CI coverage proof heap, per-side Sonar lint reports merged for the import, per-fe-app build env; `app lint --side` combines with `--sonar`.
+
 ## 4.5.1 - 2026-10-18
 - Fixed: managed CI base refs, public build values, caching and timeouts; optional quality service handling, README formatting and Supabase migration-history parsing.
 

package/ci/cli.mjs

@@ -5,7 +5,7 @@ import { readCiDeclaration, sealedKeyNames } from '../runtime/scripts/hfs/ci-dec
 import { github, refuse } from './github.mjs';
 import { setSecret } from './secret.mjs';
 import { setVariable, syncVariables } from './vars.mjs';
-import { verifyCi } from './verify.mjs';
+import { badgeVisibilityNotices, verifyCi } from './verify.mjs';
 
 const COMMANDS = {
   'secret set': ['env', 'dependabot', 'repo'],
@@ -44,18 +44,22 @@ function parse(argv) {
 
 /** Manifest and sealed key reads remain offline; only github.mjs may invoke the GitHub CLI. */
 export async function ciMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), stdin, env = process.env, tools = {} } = {}) {
+  // `ci local` runs the rendered CI on this machine (local.mjs): no manifest custody and no GitHub.
+  if (argv[0] === 'local') return (await import('./local.mjs')).ciLocalMain(argv.slice(1), { cwd, stdout, stderr, env });
   try {
     const parsed = parse(argv);
-    let declaration, sealed;
+    let doc, declaration, sealed;
     try {
-      declaration = readCiDeclaration(parseYaml(fs.readFileSync(path.join(cwd, '.starcistacks/application-stacks.yaml'), 'utf8')));
+      doc = parseYaml(fs.readFileSync(path.join(cwd, '.starcistacks/application-stacks.yaml'), 'utf8'));
+      declaration = readCiDeclaration(doc);
       sealed = sealedKeyNames(cwd, { fs });
     } catch { throw refuse('CI_DECLARATION_INVALID', 'the manifest or sealed key names could not be read'); }
     if (declaration.problems.length) throw refuse('CI_DECLARATION_INVALID', 'correct the CI declaration before using GitHub');
     const context = { ...parsed, declaration, sealed, gh: github({ cwd, env, spawn: tools.spawn }), stdin, stdout };
     if (parsed.command === 'secret set') return await setSecret(context);
-    if (parsed.command === 'var set') return setVariable(context);
+    if (parsed.command === 'var set') return await setVariable(context);
     if (parsed.command === 'var sync') return syncVariables(context);
+    context.notices = badgeVisibilityNotices({ doc, gh: context.gh, repo: context.gh.repository(parsed.options.repo) });
     return verifyCi(context);
   } catch (error) {
     stderr(`${error.code ? error.message : 'CI_USAGE: CI command could not complete'}\n`);

package/ci/local.mjs

@@ -0,0 +1,146 @@
+// local.mjs - `starci app ci local [--jobs <id,...>] [--parallel <n>] [--dry-run] [--json]`: predict the CI result while GitHub runs it. It reads the app's
+// managed .github/workflows/ci.yml (the CI standard's jobs: fast, lint per side, test per shard, coverage, build) and runs the `run:` steps of every job
+// instance on this machine, matrix values substituted, independent instances in parallel and a job after the jobs it `needs`:
+//   - steps GitHub alone can run are skipped and listed: `uses:` actions (checkout, caches, artifacts, Codecov, Sonar), the install (`npm ci`: the local
+//     install is used), the lint baseline (STARCI_BASE_REF is set to origin/<default branch>), and every step whose `if:` or text needs GitHub context
+//     (a Sonar token, a tag ref, step outputs);
+//   - the unit shards write their lcov to be/coverage/shards/shard-<i> (on GitHub each shard has its own runner and uploads it), which is where the
+//     coverage job's `starci app coverage merge` reads them;
+//   - sonar and db-types run only when --jobs names them.
+// Each instance logs to <tmp>/starci-ci-local-*/<job>[-<matrix>].log. Exit 0 every instance green, 1 one red, 2 bad usage or no ci.yml. Run steps through bash.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+
+const DEFAULT_JOBS = ['fast', 'lint', 'test', 'coverage', 'build'];
+const GITHUB_ONLY_IF = /SONAR_TOKEN\s*!=\s*''|refs\/tags|startsWith\(github\.ref|steps\.|hashFiles|github\.event/;
+const LOCAL_IF = /^(?:\$\{\{\s*)?(?:always\(\)|!cancelled\(\)|env\.SONAR_TOKEN\s*==\s*'')(?:\s*\}\})?$/;
+
+function parseArgs(argv) {
+  const opts = { jobs: null, parallel: Math.max(1, Math.min(4, Math.floor(os.cpus().length / 2))), dryRun: false, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--jobs' || arg === '--parallel') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value`);
+      if (arg === '--jobs') opts.jobs = value.split(',').map((job) => job.trim()).filter(Boolean);
+      else if (!/^[1-9]\d*$/.test(value)) throw new Error('--parallel takes a positive integer');
+      else opts.parallel = Number(value);
+      index += 1;
+    } else throw new Error(`unknown argument ${arg}`);
+  }
+  return opts;
+}
+
+/** Every combination of a one-level matrix ({side: [be, fe]} -> [{side: be}, {side: fe}]); [{}] without one. */
+function combinations(matrix) {
+  const keys = Object.keys(matrix ?? {}).filter((key) => Array.isArray(matrix[key]));
+  return keys.reduce((all, key) => all.flatMap((partial) => matrix[key].map((value) => ({ ...partial, [key]: value }))), [{}]);
+}
+
+const substitute = (text, values) => String(text).replace(/\$\{\{\s*matrix\.([A-Za-z0-9_-]+)\s*\}\}/g, (whole, key) => (Object.hasOwn(values, key) ? String(values[key]) : whole));
+
+/** The local verdict of one step: {run: command} or {skip: why}. */
+function stepPlan(step, values) {
+  const name = step.name ?? (step.uses ? String(step.uses).split('@')[0] : String(step.run ?? '').split('\n')[0].slice(0, 60));
+  if (step.uses) return { name, skip: 'a GitHub action' };
+  const condition = step.if === undefined ? null : String(step.if).trim();
+  if (condition !== null && (GITHUB_ONLY_IF.test(condition) || !LOCAL_IF.test(condition))) return { name, skip: `if: ${condition} needs GitHub context` };
+  let command = substitute(step.run ?? '', values);
+  if (/^npm ci\b/.test(command.trim())) return { name, skip: 'the install: the local node_modules is used' };
+  if (command.includes('$GITHUB_ENV') || command.includes('GITHUB_OUTPUT')) return { name, skip: 'writes GitHub step state' };
+  if (/\$\{\{/.test(command)) return { name, skip: 'needs a GitHub expression' };
+  if (name === 'unit' && values.shard !== undefined) command = `${command} --coverageDirectory coverage/shards/shard-${values.shard}`;
+  const env = Object.fromEntries(Object.entries(step.env ?? {}).filter(([, value]) => !String(value).includes('${{')).map(([key, value]) => [key, substitute(value, values)]));
+  return { name, run: command, env, cwd: step['working-directory'] ? substitute(step['working-directory'], values) : '.' };
+}
+
+/** The plan of the workflow: [{id, label, needs, steps: [{name, run|skip}]}], one entry per job instance. */
+function localPlan(workflow, jobs = null) {
+  const wanted = jobs ?? DEFAULT_JOBS;
+  const plan = [];
+  for (const [id, job] of Object.entries(workflow?.jobs ?? {})) {
+    if (!wanted.includes(id)) continue;
+    const needs = [job.needs ?? []].flat().map(String).filter((need) => wanted.includes(need));
+    for (const values of combinations(job.strategy?.matrix)) {
+      const suffix = Object.values(values).join('-');
+      plan.push({ id, label: suffix ? `${id}-${suffix}` : id, needs, steps: (job.steps ?? []).map((step) => stepPlan(step, values)) });
+    }
+  }
+  return plan;
+}
+
+function runStep(step, { root, env, log }) {
+  return new Promise((resolve) => {
+    fs.appendFileSync(log, `\n$ ${step.run}\n`);
+    const child = spawn('bash', ['-c', step.run], { cwd: path.resolve(root, step.cwd), env: { ...env, ...step.env }, windowsHide: true });
+    child.stdout.on('data', (chunk) => fs.appendFileSync(log, chunk));
+    child.stderr.on('data', (chunk) => fs.appendFileSync(log, chunk));
+    child.on('error', (error) => { fs.appendFileSync(log, `\n${error.message}\n`); resolve(1); });
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}
+
+async function runInstance(instance, { root, env, logs }) {
+  const log = path.join(logs, `${instance.label}.log`);
+  fs.writeFileSync(log, `starci app ci local: ${instance.label}\n`);
+  const started = Date.now();
+  for (const step of instance.steps.filter((entry) => entry.run !== undefined)) {
+    const code = await runStep(step, { root, env, log });
+    if (code !== 0) return { label: instance.label, ok: false, failed: step.name, seconds: Math.round((Date.now() - started) / 1000), log };
+  }
+  return { label: instance.label, ok: true, seconds: Math.round((Date.now() - started) / 1000), log };
+}
+
+/** Run the plan: instances whose needs are all done, `parallel` at a time; an instance whose need failed is not run. */
+async function runPlan(plan, { parallel, root, env, logs, report }) {
+  const results = new Map();
+  const pending = [...plan];
+  const running = new Set();
+  const doneJob = (id) => plan.filter((entry) => entry.id === id).every((entry) => results.has(entry.label));
+  const jobOk = (id) => plan.filter((entry) => entry.id === id).every((entry) => results.get(entry.label)?.ok);
+  await new Promise((resolve) => {
+    const pump = () => {
+      for (const instance of [...pending]) {
+        if (running.size >= parallel) break;
+        if (!instance.needs.every(doneJob)) continue;
+        pending.splice(pending.indexOf(instance), 1);
+        if (!instance.needs.every(jobOk)) { results.set(instance.label, { label: instance.label, ok: false, failed: `needs ${instance.needs.join(', ')}`, seconds: 0 }); continue; }
+        const task = runInstance(instance, { root, env, logs }).then((result) => { results.set(instance.label, result); report(result); running.delete(task); pump(); });
+        running.add(task);
+      }
+      if (!pending.length && !running.size) resolve();
+      else if (!running.size && pending.length) { for (const instance of pending.splice(0)) results.set(instance.label, { label: instance.label, ok: false, failed: 'its needs never completed', seconds: 0 }); resolve(); }
+    };
+    pump();
+  });
+  return plan.map((instance) => results.get(instance.label));
+}
+
+/** `starci app ci local`. */
+export async function ciLocalMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), env = process.env } = {}) {
+  let opts;
+  try { opts = parseArgs(argv); } catch (error) { stderr(`starci app ci local: ${error.message}; usage: starci app ci local [--jobs <id,...>] [--parallel <n>] [--dry-run] [--json]\n`); return 2; }
+  const file = path.join(cwd, '.github', 'workflows', 'ci.yml');
+  if (!fs.existsSync(file)) { stderr('starci app ci local: no .github/workflows/ci.yml (run starci app sync --write)\n'); return 2; }
+  const plan = localPlan(parseYaml(fs.readFileSync(file, 'utf8')), opts.jobs);
+  if (!plan.length) { stderr('starci app ci local: no job of the workflow is selected\n'); return 2; }
+  if (opts.dryRun) {
+    if (opts.json) stdout(`${JSON.stringify(plan)}\n`);
+    else for (const instance of plan) stdout(`${instance.label}${instance.needs.length ? ` (after ${instance.needs.join(', ')})` : ''}\n${instance.steps.map((step) => `  ${step.run !== undefined ? 'run ' : 'skip'} ${step.name}${step.skip ? ` - ${step.skip}` : ''}`).join('\n')}\n`);
+    return 0;
+  }
+  const logs = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-ci-local-'));
+  const defaultBranch = 'main';
+  const runEnv = { ...env, CI: 'true', STARCI_BASE_REF: env.STARCI_BASE_REF ?? `origin/${defaultBranch}`, SONAR_TOKEN: '' };
+  stdout(`starci app ci local: ${plan.length} job instance(s), ${opts.parallel} at a time; logs in ${logs}\n`);
+  const results = await runPlan(plan, { parallel: opts.parallel, root: cwd, env: runEnv, logs, report: (result) => { if (!opts.json) stdout(`${result.ok ? 'green' : 'RED  '} ${result.label} (${result.seconds}s)${result.ok ? '' : ` at ${result.failed}: ${result.log}`}\n`); } });
+  const red = results.filter((result) => !result.ok);
+  if (opts.json) stdout(`${JSON.stringify({ ok: red.length === 0, results, logs })}\n`);
+  else stdout(red.length ? `starci app ci local: ${red.length} of ${results.length} red: ${red.map((result) => result.label).join(', ')}\n` : `starci app ci local: all ${results.length} green\n`);
+  return red.length ? 1 : 0;
+}

package/ci/vars.mjs

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import { refuse, scopeArgs, scopeName } from './github.mjs';
 import { declaredEntry } from './secret.mjs';
 
@@ -15,18 +16,34 @@ function writeVariable(gh, repo, entry, value, options, stdout) {
   stdout(`set variable ${entry.name} (${scopeName(options)})\n`);
 }
 
-export function setVariable({ declaration, gh, options, name, stdout }) {
-  const entry = declaredEntry(declaration.vars, name, options), value = valueOf(entry, options.value);
+/** Owner-supplied input is read once from stdin, with one trailing newline removed and no value echoed. */
+async function ownerValueOf(options, stdin) {
+  if (Object.hasOwn(options, 'value')) throw refuse('CI_VALUE_ARGV', 'an owner-supplied variable takes its value on stdin');
+  let value;
+  if (stdin === undefined) {
+    if (process.stdin.isTTY) throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
+    value = fs.readFileSync(0, 'utf8');
+  } else value = typeof stdin === 'function' ? await stdin() : stdin;
+  value = String(value ?? '').replace(/\r?\n$/, '');
+  if (!value.length) throw refuse('CI_VALUE_EMPTY', 'an owner-supplied variable value is required on stdin');
+  return value;
+}
+
+/** Owner-supplied variables accept stdin only; other public variables retain manifest and argv agreement. */
+export async function setVariable({ declaration, gh, options, name, stdin, stdout }) {
+  const entry = declaredEntry(declaration.vars, name, options);
+  const value = entry.ownerValue ? await ownerValueOf(options, stdin) : valueOf(entry, options.value);
   writeVariable(gh, gh.repository(options.repo), entry, value, options, stdout);
   return 0;
 }
 
 /** Sync validates the whole plan first and performs no GitHub access until execution is requested. */
 export function syncVariables({ declaration, gh, options, stdout }) {
-  const plan = declaration.vars.map((entry) => ({ entry, value: valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
-  const repo = options.execute && plan.length ? gh.repository(options.repo) : undefined;
+  const plan = declaration.vars.map((entry) => ({ entry, value: entry.ownerValue ? undefined : valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
+  const repo = options.execute && plan.some((item) => !item.entry.ownerValue) ? gh.repository(options.repo) : undefined;
   for (const item of plan) {
-    if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
+    if (item.entry.ownerValue) stdout(`skip variable ${item.entry.name} (${scopeName(item.options)}): owner-supplied value; the owner runs starci app ci var set ${item.entry.name} [--env ENV] with the value on stdin\n`);
+    else if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
     else stdout(`would set variable ${item.entry.name} (${scopeName(item.options)})\n`);
   }
   return 0;

package/ci/verify.mjs

@@ -1,7 +1,8 @@
+import { badgeTokenNotices } from '../sync/readme-badges.mjs';
 import { refuse, scopeArgs, scopeName } from './github.mjs';
 
 /** Verification reports names and scopes only; values are compared in memory and excluded from findings. */
-export function verifyCi({ declaration, sealed, gh, options, stdout }) {
+export function verifyCi({ declaration, sealed, gh, options, stdout, notices = [] }) {
   const repo = gh.repository(options.repo), stores = [];
   const environments = [...new Set([...declaration.secrets, ...declaration.vars].filter((item) => item.scope === 'environment').map((item) => item.environment))].sort();
   for (const scope of [{}, ...environments.map((env) => ({ env })), { dependabot: true }]) {
@@ -29,8 +30,21 @@ export function verifyCi({ declaration, sealed, gh, options, stdout }) {
       add(sameKind.some((entry) => entry.name === row.name) ? 'CI_SCOPE_MISMATCH' : store.kind === 'secret' ? 'CI_SECRET_UNDECLARED' : 'CI_VAR_UNDECLARED', row.name, store.scope);
     }
   }
-  if (options.json) stdout(`${JSON.stringify({ ok: findings.length === 0, findings }, null, 2)}\n`);
+  if (options.json) stdout(`${JSON.stringify({ ok: findings.length === 0, findings, notices }, null, 2)}\n`);
   else if (!findings.length) stdout('CI verification passed\n');
   else for (const finding of findings) stdout(`${finding.code}: ${finding.name} (${finding.scope})\n`);
+  if (!options.json) for (const notice of notices) stdout(`${notice}\n`);
   return findings.length ? 1 : 0;
 }
+
+/** Manifest visibility wins; optional GitHub visibility discovery never changes verification findings or errors. */
+export function badgeVisibilityNotices({ doc, gh, repo }) {
+  let visibility = doc?.ci?.github?.visibility;
+  if (visibility === undefined) {
+    try {
+      const remote = gh.json(['repo', 'view', '--json', 'visibility', '--repo', repo]);
+      visibility = ['PRIVATE', 'INTERNAL'].includes(remote?.visibility) ? 'private' : 'public';
+    } catch { return []; }
+  }
+  return badgeTokenNotices({ ...doc, ci: { ...doc?.ci, github: { ...doc?.ci?.github, visibility } } }, { repository: `https://github.com/${repo}` });
+}

package/lint/run.mjs

@@ -26,7 +26,7 @@ import { STYLE_GLOB } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
 
-// --side judges only that side; root HFS findings belong to be, and Sonar always requires the full lint.
+// --side judges only that side; root HFS findings belong to be, its Sonar report stays on that side.
 export const LINT_SCHEMA = 'starci/lint@1';
 /** The side whose stylesheets stylelint judges. */
 const STYLE_SIDE = 'fe';
@@ -42,11 +42,10 @@ export function workspaceOf(workspace) {
   return rel;
 }
 
-/** Side scopes partition the full lint; Sonar requires the complete report and a frontend workspace cannot belong to be. */
+/** Side scopes partition the full lint; Sonar reports share that scope and a frontend workspace cannot belong to be. */
 function validateSide(opts) {
   if (opts.side === undefined) return;
   if (!SIDES.includes(opts.side)) throw new Error('LINT_SIDE_INVALID: --side is be or fe');
-  if (opts.sonar !== undefined) throw new Error('LINT_SIDE_SONAR_CONFLICT: --side and --sonar do not combine');
   if (opts.side === 'be' && opts.workspace !== undefined) throw new Error('LINT_SIDE_WORKSPACE_CONFLICT: --side be cannot judge a frontend workspace');
 }
 
@@ -312,7 +311,7 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
 
   let properties = '';
   try { properties = fs.readFileSync(path.join(repoRoot, 'sonar-project.properties'), 'utf8'); } catch { /* no properties: every finding keeps its own path */ }
-  const sourceRoots = sourceRootsOf(properties);
+  const sourceRoots = sourceRootsOf(properties).filter((root) => findingOnSide({ path: root }, opts.side));
   const tracked = sourceRoots.length ? trackedFiles(repoRoot) : [];
   const sonar = mergeReports([
     sonarReport(kept, { sourceRoots, tracked }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.5.1",
+  "version": "4.7.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/candidate-ci.mjs

@@ -0,0 +1,111 @@
+// candidate-ci.mjs - the candidate CI of `starci app release push` (OWNER RULING candidate-ci, 2026-10-18: "never again have main receive a release whose CI is
+// red, with the owner confirming afterwards"). The push sends the exact release sha to refs/heads/release/candidate-<version> first (the managed ci.yml triggers on
+// release/candidate-*), waits for the ci.yml run of THAT sha, and moves the default branch and the tag only when it is green:
+//   green     the newest non-cancelled run of the sha concluded success
+//   red       RELEASE_CANDIDATE_CI_RED with the run URL and the failing jobs and steps; nothing reaches the default branch. The candidate ref stays for diagnosis
+//   timeout   RELEASE_CANDIDATE_CI_TIMEOUT: no run started within the grace, or it did not end within the wait
+//   unknown   RELEASE_CI_UNKNOWN: GitHub could not be read to the end; a release never proceeds blind
+// Emergency path (documented, owner-only): the owner's `starci release ci-override --sha <sha>` record for this exact sha
+// (<git common dir>/starci-release/<sha>.ci-override.json, schema starci/ci-override@1) lets a red candidate through, and the push says so.
+// Every process goes through ctx.spawn (git, gh); the wait through ctx.sleep and ctx.now.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CANDIDATE_PREFIX = 'refs/heads/release/candidate-';
+/** The wait of the candidate run: poll interval, the grace for a run to appear, the wait for it to end (an app's ci.yml jobs time out within 45 minutes). */
+const CANDIDATE_WAIT = Object.freeze({ pollSeconds: 30, graceMinutes: 10, waitMinutes: 90 });
+const FIELDS = 'databaseId,headSha,status,conclusion,url,event,createdAt';
+const SHA = /^[a-f0-9]{40}$/u;
+const PASSING = new Set(['success', 'neutral', 'skipped']);
+
+/** The candidate ref of the release tag `tag` with the app's tag prefix: refs/heads/release/candidate-<version>. */
+export const candidateRef = (tag, prefix = 'v') => `${CANDIDATE_PREFIX}${String(tag).startsWith(prefix) ? String(tag).slice(prefix.length) : String(tag)}`;
+
+function run(ctx, command, args) {
+  try { return ctx.spawn(command, args, { cwd: ctx.cwd }); } catch { return { status: null }; }
+}
+
+function jsonOf(result) {
+  if (!result || result.error || result.status !== 0) return null;
+  try { return JSON.parse(result.stdout); } catch { return null; }
+}
+
+/** pending (no run) | running | green | red over the runs of the sha; a cancelled run is no verdict. Pure. */
+export function candidateVerdict(rows) {
+  const runs = (rows ?? []).filter((row) => row && row.conclusion !== 'cancelled');
+  runs.sort((a, b) => Date.parse(b.createdAt ?? 0) - Date.parse(a.createdAt ?? 0) || Number(b.databaseId) - Number(a.databaseId));
+  const newest = runs[0];
+  if (!newest) return { state: 'pending', run: null };
+  if (newest.status !== 'completed') return { state: 'running', run: newest };
+  return { state: newest.conclusion === 'success' ? 'green' : 'red', run: newest };
+}
+
+/** One read of the ci.yml runs of `sha`: {ok, state, run} or {ok: false}. */
+function readCandidateRun(ctx, sha) {
+  const rows = jsonOf(run(ctx, 'gh', ['run', 'list', '--workflow', 'ci.yml', '--commit', sha, '--limit', '20', '--json', FIELDS]));
+  if (!Array.isArray(rows)) return { ok: false };
+  return { ok: true, ...candidateVerdict(rows.filter((row) => !row.headSha || row.headSha === sha)) };
+}
+
+/** The failing jobs and steps of a run: ['job (conclusion): step, step']; [] when unreadable. */
+export function failingJobs(ctx, runRow) {
+  if (!/^\d+$/u.test(String(runRow?.databaseId ?? ''))) return [];
+  const reply = jsonOf(run(ctx, 'gh', ['run', 'view', String(runRow.databaseId), '--json', 'jobs']));
+  return (reply?.jobs ?? []).filter((job) => job.conclusion && !PASSING.has(job.conclusion)).map((job) => {
+    const steps = (job.steps ?? []).filter((step) => step.conclusion && !PASSING.has(step.conclusion)).map((step) => step.name);
+    return `${job.name} (${job.conclusion})${steps.length ? `: ${steps.join(', ')}` : ''}`;
+  });
+}
+
+/** Only a complete starci/ci-override@1 record for this exact commit can excuse a red candidate. */
+export function overrideOf(ctx, sha) {
+  if (!SHA.test(String(sha))) return null;
+  const common = run(ctx, 'git', ['rev-parse', '--git-common-dir']);
+  if (common.error || common.status !== 0 || !String(common.stdout ?? '').trim()) return null;
+  const file = path.join(path.resolve(ctx.cwd, String(common.stdout).trim()), 'starci-release', `${sha}.ci-override.json`);
+  try {
+    const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (record.schema !== 'starci/ci-override@1' || record.sha !== sha || typeof record.reason !== 'string' || !record.reason.trim() || typeof record.by !== 'string' || !record.by.trim() || typeof record.at !== 'string' || !Number.isFinite(Date.parse(record.at))) return null;
+    return record;
+  } catch { return null; }
+}
+
+/** Poll the candidate run of `sha` until green or red, or the grace (no run) or the wait passes: {state: green|red|timeout|unstarted|unknown, run}. */
+export async function waitForCandidate(ctx, sha, wait = CANDIDATE_WAIT) {
+  const started = ctx.now();
+  let readable = null;
+  for (;;) {
+    const seen = readCandidateRun(ctx, sha);
+    if (seen.ok) readable = seen;
+    if (seen.ok && (seen.state === 'green' || seen.state === 'red')) return seen;
+    const elapsed = ctx.now() - started;
+    if (seen.ok && seen.state === 'pending' && elapsed >= wait.graceMinutes * 60_000) return { state: 'unstarted', run: null };
+    if (elapsed >= wait.waitMinutes * 60_000) return readable ? { state: 'timeout', run: readable.run } : { state: 'unknown', run: null };
+    await ctx.sleep(wait.pollSeconds * 1000);
+  }
+}
+
+/**
+ * The candidate step of the push: push HEAD to the candidate ref (through the pre-push hook), wait for its CI. {ok, lines, data: {ref, state, run, failing, override}}.
+ * ok only on green, or on red under the owner's override record for this exact sha.
+ */
+export async function candidateStep(ctx, { head, tag, prefix, remote, wait = CANDIDATE_WAIT }) {
+  const ref = candidateRef(tag, prefix);
+  const lines = [];
+  const pushed = run(ctx, 'git', ['push', remote, `+${head}:${ref}`]);
+  if (pushed.status !== 0) return { ok: false, lines: [`candidate      push of ${head.slice(0, 10)} to ${ref} failed: ${String(pushed.stderr ?? '').trim().split('\n')[0]}`], data: { ref, state: 'push-failed' } };
+  lines.push(`candidate      pushed ${head.slice(0, 10)} to ${remote} ${ref}; waiting for its ci.yml run`);
+  const seen = await waitForCandidate(ctx, head, wait);
+  const url = seen.run?.url ? ` ${seen.run.url}` : '';
+  if (seen.state === 'green') return { ok: true, lines: [...lines, `candidate CI   green${url}`], data: { ref, state: 'green', run: seen.run } };
+  if (seen.state === 'red') {
+    const failing = failingJobs(ctx, seen.run);
+    const record = overrideOf(ctx, head);
+    const detail = failing.length ? failing.join('; ') : 'the failing jobs could not be read';
+    if (record) return { ok: true, lines: [...lines, `candidate CI   RED${url}; failing: ${detail}`, `RELEASE_CANDIDATE_CI_RED overridden by the owner (${record.by}): ${record.reason}`], data: { ref, state: 'red', run: seen.run, failing, override: { by: record.by, reason: record.reason, at: record.at } } };
+    return { ok: false, lines: [...lines, `RELEASE_CANDIDATE_CI_RED: the ci.yml run of ${head.slice(0, 10)} on ${ref} is red${url}; failing: ${detail}. Nothing reached the default branch; the candidate ref stays for diagnosis`], data: { ref, state: 'red', run: seen.run, failing } };
+  }
+  if (seen.state === 'unstarted') return { ok: false, lines: [...lines, `RELEASE_CANDIDATE_CI_TIMEOUT: no ci.yml run started for ${head.slice(0, 10)} on ${ref} within ${wait.graceMinutes} minutes (does .github/workflows/ci.yml trigger on release/candidate-*? run starci app sync)`], data: { ref, state: 'unstarted' } };
+  if (seen.state === 'timeout') return { ok: false, lines: [...lines, `RELEASE_CANDIDATE_CI_TIMEOUT: the ci.yml run of ${head.slice(0, 10)} did not end within ${wait.waitMinutes} minutes${url}`], data: { ref, state: 'timeout', run: seen.run } };
+  return { ok: false, lines: [...lines, `RELEASE_CI_UNKNOWN: GitHub could not be read for the candidate ${head.slice(0, 10)} on ${ref}; a release never proceeds blind`], data: { ref, state: 'unknown' } };
+}

package/release/gate.mjs

@@ -10,7 +10,6 @@ import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
 import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
 import { firstLine, lines, tool } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
-import { latestDefaultBranchCi, requireGreenCi } from './ci-red.mjs';
 
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
 const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
@@ -346,14 +345,14 @@ function summaryOf(result) {
  */
 export async function releaseGate(ctx, config, options = {}) {
   if (options.sonar) config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
-  const ci = latestDefaultBranchCi({ spawn: ctx.spawn, cwd: ctx.cwd, defaultBranch: config.defaultBranch });
-  const ciLines = requireGreenCi(ctx, ci);
+  // The CI verdict of a release is the candidate run of its own sha, judged by `starci app release push` (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18):
+  // the gate no longer refuses over the latest default-branch run.
   const facts = inspect(ctx, config, options);
   const common = releaseDir(ctx);
   const recordPath = path.join(common, `${facts.head}.l4.json`);
   const dir = path.join(common, facts.head.slice(0, 12));
-  const plan = [...ciLines, ...facts.out, ...planLines(config, facts, dir, recordPath)];
-  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name), ci: { state: ci.state, notices: ciLines } };
+  const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
+  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name) };
   if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
   if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
   const results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform });

package/release/push.mjs

@@ -1,11 +1,14 @@
 // push.mjs - `starci app release push`: sends the default branch and the release tag to the remote in ONE atomic push through the repository's own
 // pre-push hook (never --no-verify). It requires what the hook requires: an annotated release tag on HEAD and the L4 record of the gate for that
 // head and tag. `git push --dry-run --atomic` always runs first (the hook's verdict is the proof) and any failure refuses the push.
+// With --execute the exact sha first goes to its candidate ref refs/heads/release/candidate-<version> and the push waits for the ci.yml run of that sha
+// (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18): only a green candidate (or the owner's sha-bound override record) moves the branch and the tag.
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
 import { annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
+import { candidateRef, candidateStep } from './candidate-ci.mjs';
 
 const VERDICT = /RIGHTS_PUSH_NOT_RELEASE|pre-push|failed to push|Everything up|->/u;
 
@@ -95,7 +98,9 @@ export async function releasePush(ctx, config, options = {}) {
   const red = [];
   const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...tagRefs(ctx, { remote, tag: gate.tag }, red)];
   data.refs = refs;
-  out.push(`plan           git push --atomic ${remote} ${refs.join(' ') || '(nothing)'}`);
+  const candidate = refs.length > 0 ? candidateRef(gate.tag, config.tagPrefix) : null;
+  if (candidate) out.push(`plan           git push ${remote} +${head.slice(0, 10)}:${candidate}, wait for its ci.yml run to be green, then git push --atomic ${remote} ${refs.join(' ')}`);
+  else out.push(`plan           git push --atomic ${remote} (nothing)`);
   if (refs.length === 0 && red.length === 0) return { ok: true, lines: [...out, `already pushed: ${remote}/${branch} holds HEAD and ${gate.tag} is on ${remote}. Nothing to do.`], data };
   if (refs.length > 0) {
     const hook = probe(ctx, remote, refs, red);
@@ -104,6 +109,10 @@ export async function releasePush(ctx, config, options = {}) {
   }
   if (red.length > 0) return refuse(out, red, data, options.execute === true ? 'nothing pushed.' : 'dry run: nothing pushed.');
   if (options.execute !== true) return { ok: true, lines: [...out, 'dry run: nothing pushed. ready; re-run with --execute.'], data };
+  const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
+  data.candidate = judged.data;
+  out.push(...judged.lines);
+  if (!judged.ok) return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
   const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
   if (run.code !== 0) return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}`], data };
   return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ')}`], data: { ...data, pushed: true } };

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.3
+    version: 3.4.5
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.3
+    version: 8.4.5
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.5.1
+    version: 1.7.0
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.5.1
+    version: 4.7.0
     group: starci
     install: registry
     side: both
@@ -466,6 +466,11 @@ pins:
     group: framework
     side: be
     why: 'the GraphQL transport of every back end (be.transport.graphql) that the front end calls; the ecommerce-app resolution on 2026-10-13. Stays on 13.x for alpha.18: the npm-audit advisory fixed by 14.0.3 (semver major) is a documented accepted exception, upgrade deferred to alpha.19 (owner ruling graphql-13-advisory-accepted-until-a19, 2026-10-16).'
+  '@graphql-tools/utils':
+    version: 12.1.0
+    group: framework
+    side: be
+    why: 'an npm override of every app root (and of the examples that serve GraphQL), never a declared dependency: @nestjs/graphql 13.x pulls @graphql-tools/utils <=12.0.0, which npm audit --audit-level=high reports (GHSA-7mx3-vvmw-hjmv, prototype pollution in mergeDeep). 12.1.0 is a fixed release on the same major and the lowest one every declared range accepts (@graphql-tools/schema and /merge, used at runtime, require ^12.1.0; NIVO v0.2.1 6a1d8e80 overrides 12.0.4, below that range), so the advisory closes without the breaking @nestjs/graphql 14. DROP this pin and the override when @nestjs/graphql 14 is adopted (owner ruling graphql-tools-utils-override, 2026-10-18).'
   '@nestjs/apollo':
     version: 13.4.5
     group: framework